Working With Custom Hooks: OnPageCategorizationChange
Taxonomy categories can be applied to content items in the CMS and are primarily used for querying, filtering, and sorting content on a website. We look at how this custom hook can be used to set paramaters around how and when a category is changed on a page.
In previous articles, we introduced the taxonomy system in Ingeniux CMS. Located in the Administration Section of the platform, the Taxonomy Manager is where users create and manage a hierarchical structure of categories that are then applied to pages, components, and assets.
In this article, we’ll explore the OnPageCategorizationChange custom hook, which would trigger whenever a category is added or removed to a page or component in the Site Tree.
To change the categorization of a Content Item, it must be checked out and assigned to the user attempting to make the change.
Working with categories in the Taxonomy Manager can sometimes get tricky because categories are often applied to large amounts of content and are pulled into pages as filtering mechanisms (e.g., a search page) via Taxonomy Navigation Elements on schemas. As a result, one small change can have unforeseen effects.
How To Trigger the Hook
This method is triggered through the following actions:
- Adding or removing a category on a page or component through the Categorize tab in the Site area and saving.
- Adding or removing a category on a page or component through the Associations tab of a category in Administration > Taxonomy.
- Initiating a script that adds or removes a category from a page or component.
When to Use This Custom Hook
CMS administrators might be interested in using this custom hook to:
- Limit or block the removal or duplication of high-level categories.
- Notify content owners when categorization changes have been made to their content.
- Disallow publishing until management approval is complete.
Considerations
Take care when using this hook to add or remove other categories, as an infinite loop could be triggered.
If an error is thrown after a category is added or removed, the user will have to undo their actions prior to navigating way from the Categorize tab, since leaving the tab will initiative a save.
Example
Add the ID of the Page to the External ID Field in the Category for Tracking
In the CMS, components are commonly used to build content blocks that can be shared or reused on pages throughout the site. Sometimes, these components pull in and display lists of content based on taxonomy category, like latest news, recent blog posts, or upcoming events. This taxonomy-driven feature makes it easy to share relevant and dynamic content.
Overtime, categories sometimes adjust and change. For example, categories might be re-organized in the structure of the Taxonomy Tree or be renamed. A user changing the name of a category might not remember that there is a component that references that category. To keep content organized and updated, this script assists the user by attaching the component to the category and giving the components to the editor’s group if/when the category is renamed.
First, the content strategy is to store the component IDs in a comma separated list in the External ID of the matching category. This will give easy access to those items later when you want to track updates.
The code checks the existence of a page and performs operations related to associating the page with a category. The specific actions taken depend on the value of the "action" parameter, which is an enum of which action was taken: associating (0) or unassociating (1) the category.
This example code checks if the page is not null using the condition. If the condition is true, the code block within the curly braces will be executed.
Inside the if statement, there is another conditional check using the variable "action". If "action" is equal to 0, the code block within the next set of curly braces will be executed. Otherwise, the code block within the "else" block will be executed.
Within the first conditional block, there is an additional check using the method "string.IsNullOrWhiteSpace(category.ExternalID)" to determine if the variable "category.ExternalID" is null, empty, or contains only whitespace. If it is not null or empty, the code appends the value of the External ID attribute on the category with a comma and the value of the ID of the page. If it is null or empty, the code assigns the value of the page ID to the External ID attribute.
In the second conditional block (the "else" block), the code is meant to unassociate a content item with a category. It first checks if External ID is not null or empty. If it is not, the code replaces occurrences of the page ID followed by a comma (",") with an empty string, and also replaces occurrences of just the asset ID with an empty string.
if (page != null)
{
// Associate a content item with category
if (action == 0)
{
if (!string.IsNullOrWhiteSpace(category.ExternalID))
{
category.ExternalID = category.ExternalID + "," + page.Id;
}
else
{
category.ExternalID = page.Id;
}
}
else
{
//Unassociate a content item with category
//Then Remove prior page id
if (!string.IsNullOrWhiteSpace(category.ExternalID))
{
category.ExternalID = category.ExternalID.Replace(page.Id + ",", "").Replace(page.Id, "");
}
}
}
Ways to Extend the Functionality Further
There are several extensions and enhancements that could be made to improve the functionality and efficiency of the code:
- Error handling: Add appropriate error handling mechanisms, such as try-catch blocks, to handle any potential exceptions that may occur during execution. This will help in identifying and gracefully handling errors, preventing crashes or unexpected behavior.
- Parameter validation: Validate the inputs to ensure they are not null before executing the code. This will prevent potential null reference exceptions and improve the reliability of the code.
- Refactoring: The strings could be split on the comma to avoid ambiguity.
There are no comments yet.